'\" te
.\" Copyright (c) 2004 Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH PM-COMPONENTS 9P "May 23, 2021"
.SH NAME
pm-components \- Power Management device property
.SH DESCRIPTION
A device is power manageable if the power consumption of the device can be
reduced when it is idle. In general, a power manageable device consists of a
number of power manageable hardware units called components. Each component is
separately controllable and has its own set of power parameters.
.sp
.LP
An example of a one-component power manageable device is a disk whose spindle
motor can be stopped to save power when the disk is idle. An example of a
two-component power manageable device is a frame buffer card with a connected
monitor. The frame buffer electronics (with power that can be reduced when not
in use) comprises the first component. The second component is the monitor,
which can enter in a lower power mode when not in use. The combination of frame
buffer electronics and monitor is considered as one device by the system.
.sp
.LP
In the Power Management framework, all components are considered equal and
completely independent of each other. If this is not true for a particular
device, the device driver must ensure that undesirable state combinations do
not occur. Each component is created in the idle state.
.sp
.LP
The \fBpm-components\fR property describes the Power Management model of a
device driver to the Power Management framework. It lists each power manageable
component by name and lists the power level supported by each component by
numerical value and name. Its syntax and interpretation is described below.
.sp
.LP
This property is only interpreted by the system immediately after the device
has successfully attached, or upon the first call into Power Management
framework, whichever comes first. Changes in the property made by the driver
after the property has been interpreted will not be recognized.
.sp
.LP
\fBpm-components\fR is a string array property. The existence of the
\fBpm-components\fR property indicates that a device implements power
manageable components and describes the Power Management model implemented by
the device driver. The existence of \fBpm-components\fR also indicates to the
framework that device is ready for Power Management if automatic device Power
Management is enabled. See \fBpower.conf\fR(5).
.sp
.LP
The \fBpm-component\fR property syntax is:
.LP
.nf
pm-components="NAME=component name","numeric power level=power level name",  "numeric power level=power level name"  [, "numeric power level=power level name" ...]  [, "NAME=component name", "numeric power level=power level name",  "numeric power level=power level name" [, "numeric power level=power level name"...]...];
.fi

.sp
.LP
The start of each new component is represented by a string consisting of
\fBNAME=\fR followed by the name of the component. This should be a short name
that a user would recognize, such as "Monitor" or "Spindle Motor." The
succeeding elements in the string array must be strings consisting of the
numeric value (can be decimal or 0x <hexadecimal number>) of a power level the
component supports, followed by an equal sign followed by a short descriptive
name for that power level. Again, the names should be descriptive, such as
"On," "Off," "Suspend", "Standby," etc. The next component continues the array
in the same manner, with a string that starts out \fBNAME=\fR, specifying the
beginning of a new component (and its name), followed by specifications of the
power levels the component supports.
.sp
.LP
The components must be listed in increasing order according to the component
number as interpreted by the driver's \fBpower\fR(9E) routine. (Components are
numbered sequentially from 0). The power levels must be listed in increasing
order of power consumption. Each component must support at least two power
levels, or there is no possibility of power level transitions. If a power level
value of 0 is used, it must be the first one listed for that component. A power
level value of 0 has a special meaning (off) to the Power Management framework.
.SH EXAMPLES
An example of a \fBpm-components\fR entry from the \fB\&.conf\fR file of a
driver which implements a single power managed component consisting of a disk
spindle motor is shown below. This is component 0 and it supports 2 power
level, which represent spindle stopped or full speed.
.sp
.in +2
.nf
pm-components="NAME=Spindle Motor", "0=Stopped", "1=Full Speed";
\&...
.fi
.in -2
.sp

.sp
.LP
Below is an example of how the above entry would be implemented in the
\fBattach\fR(9E) function of the driver.
.sp
.in +2
.nf
static char *pmcomps[] = {
  "NAME=Spindle Motor",
    "0=Stopped",
    "1=Full Speed"
};

\&...

xxattach(dev_info_t *dip, ddi_attach_cmd_t cmd)
{
\&...
    if (ddi_prop_update_string_array(DDI_DEV_T_NONE, dip, "pm-components",
       &pmcomp[0], sizeof (pmcomps) / sizeof (char *)) !=DDI_PROP_SUCCESS)
		       goto failed;
}
.fi
.in -2
.sp

.sp
.LP
Below is an example for a frame buffer which implements two components.
Component 0 is the frame buffer electronics which supports four different power
levels. Component 1 represents the state of Power Management of the attached
monitor.
.sp
.in +2
.nf
pm-components="NAME=Frame Buffer", "0=Off"
	"1=Suspend", "2=Standby", "3=On",
		"NAME=Monitor", "0=Off", "1=Suspend", "2=Standby,"
		"3=On;
.fi
.in -2
.sp

.SH ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface stability	Committed
.TE

.SH SEE ALSO
.BR pm (4D),
.BR power.conf (5),
.BR attach (9E),
.BR detach (9E),
.BR ddi_prop_update_string_array (9F),
.BR pm_busy_component (9F),
.BR pm_idle_component (9F)
.sp
.LP
\fIWriting Device Drivers\fR
